From 32d1defc762f5c2ef9c7c25d40556cc04f9426e4 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Fri, 1 Oct 2010 09:10:52 -0400
Subject: [PATCH] GDK docs: help gtk-doc understand
 gdk_window_invalidate_maybe_recurse

---
 docs/reference/gdk/gdk3-sections.txt |  3 +--
 gdk/gdkwindow.c                      | 16 +++++++---------
 gdk/gdkwindow.h                      | 25 ++++++++++++++++++++-----
 3 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt
index c8aa53aadb..3536055c37 100644
--- a/docs/reference/gdk/gdk3-sections.txt
+++ b/docs/reference/gdk/gdk3-sections.txt
@@ -389,6 +389,7 @@ gdk_window_end_paint
 <SUBSECTION>
 gdk_window_invalidate_rect
 gdk_window_invalidate_region
+GdkWindowChildFunc
 gdk_window_invalidate_maybe_recurse
 gdk_window_get_update_area
 gdk_window_freeze_updates
@@ -442,7 +443,6 @@ gdk_window_get_position
 gdk_window_get_root_origin
 gdk_window_get_frame_extents
 gdk_window_get_origin
-gdk_window_get_deskrelative_origin
 gdk_window_get_root_coords
 gdk_window_get_pointer
 gdk_window_get_device_position
@@ -625,7 +625,6 @@ GDK_THREADS_LEAVE
 gdk_threads_init
 gdk_threads_enter
 gdk_threads_leave
-gdk_threads_mutex
 gdk_threads_set_lock_functions
 gdk_threads_add_idle
 gdk_threads_add_idle_full
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 1479798b55..e0ef633f37 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -4368,12 +4368,11 @@ impl_window_add_update_area (GdkWindowObject *impl_window,
  * system has already cleared the area).
  */
 static void
-gdk_window_invalidate_maybe_recurse_full (GdkWindow       *window,
+gdk_window_invalidate_maybe_recurse_full (GdkWindow            *window,
 					  const cairo_region_t *region,
-					  ClearBg          clear_bg,
-					  gboolean       (*child_func) (GdkWindow *,
-									gpointer),
-					  gpointer   user_data)
+					  ClearBg               clear_bg,
+                                          GdkWindowChildFunc    child_func,
+					  gpointer              user_data)
 {
   GdkWindowObject *private = (GdkWindowObject *)window;
   GdkWindowObject *impl_window;
@@ -4489,11 +4488,10 @@ gdk_window_invalidate_maybe_recurse_full (GdkWindow       *window,
  * invalidated.
  **/
 void
-gdk_window_invalidate_maybe_recurse (GdkWindow       *window,
+gdk_window_invalidate_maybe_recurse (GdkWindow            *window,
 				     const cairo_region_t *region,
-				     gboolean       (*child_func) (GdkWindow *,
-								   gpointer),
-				     gpointer   user_data)
+                                     GdkWindowChildFunc    child_func,
+				     gpointer              user_data)
 {
   gdk_window_invalidate_maybe_recurse_full (window, region, CLEAR_BG_NONE,
 					    child_func, user_data);
diff --git a/gdk/gdkwindow.h b/gdk/gdkwindow.h
index 84fc1e8588..5f2c6cbbc3 100644
--- a/gdk/gdkwindow.h
+++ b/gdk/gdkwindow.h
@@ -802,11 +802,26 @@ void       gdk_window_invalidate_rect           (GdkWindow          *window,
 void       gdk_window_invalidate_region         (GdkWindow          *window,
 					         const cairo_region_t    *region,
 					         gboolean            invalidate_children);
-void       gdk_window_invalidate_maybe_recurse  (GdkWindow          *window,
-						 const cairo_region_t    *region,
-						 gboolean (*child_func) (GdkWindow *, gpointer),
-						 gpointer   user_data);
-cairo_region_t *gdk_window_get_update_area     (GdkWindow    *window);
+
+/**
+ * GdkWindowChildFunc:
+ * @window: a #GdkWindow
+ * @user_data: user data
+ *
+ * A function of this type is passed to gdk_window_invalidate_maybe_recurse().
+ * It gets called for each child of the window to determine whether to
+ * recursively invalidate it or now.
+ *
+ * Returns: %TRUE to invalidate @window recursively
+ */
+typedef gboolean (*GdkWindowChildFunc)          (GdkWindow *window,
+                                                 gpointer   user_data);
+
+void       gdk_window_invalidate_maybe_recurse  (GdkWindow            *window,
+						 const cairo_region_t *region,
+						 GdkWindowChildFunc    child_func,
+						 gpointer              user_data);
+cairo_region_t *gdk_window_get_update_area      (GdkWindow            *window);
 
 void       gdk_window_freeze_updates      (GdkWindow    *window);
 void       gdk_window_thaw_updates        (GdkWindow    *window);
-- 
2.30.2